QuickTime 4 Reference

High-Level Functions

These functions give you high-level pre-packaged access to the video effects architecture. These functions are designed to be easy to use and give you access to the most common uses of the QuickTime Video Effects architecture.

QTGetEffectsList

The QTGetEffectsList function returns a QTAtomContainer holding a list of the currently installed effects components. You can constrain the list to certain types of effects, such as those that take two sources. Use this function to obtain a list of effects that you can pass to "QTCreateStandardParameterDialog" .



 
OSErr QTGetEffectsList (

                     QTAtomContainer *returnedList,

                     long minSources,

                     long maxSources,

                     QTEffectListOptions getOptions);

returnedList: If QTGetEffectsList returns noErr , this parameter contains a newly created QTAtomContainer holding a list of their currently installed effects. Any data stored in the parameter on entry is overwritten by the list of effects. It is the responsibility of the calling application to dispose of the storage by calling QTDisposeAtomContainer once the list is no longer required.
minSources: The minimum number of sources that an effect must have to be added to the list. Pass -1 as this parameter to specify no minimum.
maxSources: The maximum number of sources that an effect can have to be added to the list. Pass -1 as this parameter to specify no maximum.
getOptions: Options that control which effects are added to the list. The values that getOptions can take are:; 0 - Include every effect, except the "none" effect (and any prohibited by the values of minSources and maxSources ); elOptionsIncludeNoneInList - Include the "none" effect in the returned list. The "none" effect does nothing.

DISCUSSION

This function returns the list of currently installed effects in the returnedList parameter. The returned list contains two atoms for each effect component. The first atom, of type kEffectNameAtom contains the name of the effect. The second atom, of type kEffectTypeAtom contains the type of the effect, which is the sub-type of the effect component. This list is sorted alphabetically on the names of the effects.

The minSources and maxSources parameters allow you to restrict which effects are returned in the list, by specifying the minimum and maximum number of sources that qualifying effects can have. You can also specify whether the "none" effect is included in the list using the getOptions parameter.

SPECIAL CONSIDERATIONS

The calling application is responsible for disposing of the QTAtomContainer returned in returnedList . The application should do this by calling QTDisposeAtomContainer once it has finished using the parameters description.

This function can take a fairly long time to execute, as it searches the system for installed effects components. You will normally want to call this function once when your application starts, or after a pair of suspend and resume events.

RESULT CODES

`ParamErr`	-50	The value passed to `returnedList` was not a valid `QTAtomContainer` .
Any memory error	n/a	Memory errors returned by `QTNewAtomContainer` can also be returned by `QTGetEffectsList` .

QTCreateStandardParameterDialog

The QTCreateStandardParameterDialog function creates a dialog box that allows the user to choose an effect from the list of effects passed to the function. The user can also set the values of the parameters of the effect chosen. The standard dialog includes a preview of the effect.



 
OSErr QTCreateStandardParameterDialog (

                     QTAtomContainer effectList,

                     QTAtomContainer parameters,

                     QTParameterDialogOptions dialogOptions,

                     QTParameterDialog *createdDialog);

effectList: A list of the effects that the user can choose from. In most cases you should call QTGetEffectsList to generate this list. If you passNIL in this parameter, QTCreateStandardParameterDialog calls QTGetEffectsList to retrieve the list of all currently installed effects; this list is then presented to the user.
parameters: An effect description containing the default parameter values for the effect. If the effect named in the parameter description is in effectlist , that effect is displayed when the dialog is first shown, and its parameter values are set from the parameter description. Pass in an empty atom container to have the dialog box display the first effect in the list, set to its default parameters.; On return, this atom container holds an effect description for the effect selected by the user, including the parameter settings. This effect description can then be added to the media of an effect track. You will need to add source atoms to this container for effects that require sources.
dialogOptions: Options to control the behavior of the dialog. The valid options are the same as those used by ImageCodecCreateStandardParameterDialog (see "ImageCodeCreateStandardParameterDialog" for details).
createdDialog: Returns a reference to the dialog box that is created by this function. You pass this value to the high-level functions QTIsStandardParameterDialogEvent and QTDismissStandardParameterDialog .

DISCUSSION

This function creates and displays a standard parameter dialog box that allows the user to choose an effect from the list in the effectsList parameter. The dialog box also allows the user to choose values for the parameters of the effect, to preview the effects as they choose and customize them, and to get more information about each effect.

Your application must call the WaitNextEvent and QTIsStandardParameterDialogEvent functions to allow the user to interact with the dialog box that is shown.

Note
The dialog box will remain hidden until the first event is processed by QTIsStandardParameterDialogEvent . At this point, the dialog box will be displayed.

The list of effects passed in the effectList parameter should be in the format defined in "QTGetEffectsList" . You should use the QTGetEffectsList function to generate this list.

The parameters parameter returns an effect description data structure, as described in "Creating an Effect Description" . If you pass an empty QTAtomContainer as this parameter, the dialog box will be showing the first effect in effectsList when it appears, otherwise it will display the effect named in the effect description.

The value returned in the createdDialog parameter is a reference to the dialog box that is created. You should only pass this value to the QTIsStandardParameterDialogEvent and QTDismissStandardParameterDialog functions.

You can modify the default behavior of the dialog box that is created by calling QTStandardParameterDialogDoAction (see "QTStandardParameterDialogDoAction" .

RESULT CODES

`ParamErr`	-50	The `createdDialog` parameter contained an illegal value. This parameter must contain the address of a `QTParameterDialog` .
`NoCodecErr`	-8961	The `effectsList` parameter does not contain a valid list of effects.

QTIsStandardParameterDialogEvent

The QTIsStandardParameterDialogEvent function determines if an event returned from WaitNextEvent is processed by a standard parameter dialog box created by QTCreateStandardParameterDialog .



 
OSErr QTIsStandardParameterDialogEvent (

                     EventRecord *pEvent,

                     QTParameterDialog createdDialog);

pEvent: The event returned from a call to WaitNextEvent .
createdDialog: The reference to the standard parameters dialog box that is returned by QTCreateStandardParameterDialog .

DISCUSSION

This function determines whether an operating system event, as returned by a call to the WaitNextEvent function, is processed by the standard parameters dialog box created by QTCreateStandardParameterDialog . If the event is processed by the dialog box it is handled by this function, otherwise it is an event that your application is responsible for processing.

After you create a standard parameter dialog box, you must pass every event received from WaitNextEvent through the QTIsStandardParameterDialogEvent function to determine if your application should handle the event. Once the dialog box has been confirmed or cancelled by the user, you should no longer call the QTIsStandardParameterDialogEvent function.

You determine the status of the event by examining the return code of the QTIsStandardParameterDialogEvent function. This can be one of the following values:

featureUnsupported: The event was not handled by the standard parameter dialog box, so your application should handle it in the usual way.
noErr: The event was handled by the standard parameter dialog box, so you should not process it yourself; instead you should call WaitNextEvent to retrieve further events.
codecParameterDialogConfirm: The event was handled by the standard parameter dialog box, and the user has clicked the OK button of the dialog box. The effect description that you passed in the parameters parameter to the QTIsStandardParameterDialogEvent function has been filled to reflect the choices the user made in the dialog box. You should call the QTDismissStandardParameterDialog function to close the dialog box.
userCanceledErr: The event was handled by the standard parameter dialog box, and the user has clicked the Cancel button of the dialog box. You should call the QTDismissStandardParameterDialog function to close the dialog box.

QTDismissStandardParameterDialog

The QTDismissStandardParameterDialog function closes a standard parameter dialog box that was created using the QTCreateStandardParameterDialog function. All memory associated with the dialog box is disposed of.



 
OSErr QTDismissStandardParameterDialog (QTParameterDialog createdDialog);

createdDialog: The reference to the standard parameters dialog box that is returned by QTCreateStandardParameterDialog .

QTStandardParameterDialogDoAction

The QTStandardParameterDialogDoAction function allows you to change some of the default behaviors of the standard parameter dialog box.



 
OSErr QTStandardParameterDialogDoAction(

                     QTParameterDialog createdDialog,

                     long action, 

                     void *params);

createdDialog: The reference to the dialog box created by calling QTCreateStandardParameterDialog .
action: Determines which of the actions supported by this function will be performed.
params: The (optional) parameter to the action. The type passed in this parameter depends on the value of the action parameter.

DISCUSSION

The QTStandardParameterDialogDoAction function allows you to change some of the default behaviors of a standard parameter dialog box you create using the QTCreateStandardParameterDialog function. To choose which of the available customizations to perform, pass an action selector value in the action parameter and, optionally, a single parameter in params .

The following list details the valid action selectors:

pdActionSetAppleMenu: Use this selector to make the Apple menu available while the standard parameter dialog box is active. Pass the MenuHandle of the Apple menu in the params parameter.
pdActionSetEditMenu: Use this action to make your application's Edit menu available while the standard parameters dialog box is active.Pass the MenuHandle of the Edit menu in the params parameter.
pdActionSetPreviewPicture: Use this action to change the images that are used in the preview window of the standard parameters dialog box. QuickTime provides default images but you may wish, for example, to use thumbnail images taken from your application instead. The params parameter contains a QTParamPreviewPtr referencing the image to use (see "Parameter Dialog Box Preview Image Specifier" ).
pdActionSetDialogTitle: Sets the title of the standard parameters dialog box. The params parameters contains a Pascal Str255 string.
pdActionGetSubPanelMenu: Returns a list of the sub-panels used by the standard parameters dialog box. If there are more parameter controls than can fit into the available area of the dialog box, the parameters are automatically split into sub-panels (usually by segmenting the set of parameters by group). The pop-up menu used to switch between the panels is returned as a MenuHandle in the params parameter.
pdActionActivateSubPanel: Sets the current sub-panel. The params parameter contains a long integer that is the number of the panel to be displayed.
pdActionConductStopAlert: Displays a Stop alert. The params parameter contains a StringPtr that is displayed in the alert. This feature can be used in conjunction with the ImageCodecValidateParameters function to inform the user when invalid parameter values have been entered.

QTGetEffectSpeed

The QTGetEffectSpeed function returns the speed of the effect, expressed in frames-per-second.



 
OSErr QTGetEffectSpeed (

                     QTAtomContainer parameters,

                     Fixed *pFPS);

parameters: Contains parameter values for the effect.
pFPS: The speed of the effect is returned in this parameter. Speed is expressed in frames per second.

DISCUSSION

This function returns the execution speed of an effect in frames-per-second. The value returned should not be treated as an absolute measurement of effect performance. In particular, most effects only return one value, regardless of parameter settings and hardware. This value is an estimate of execution speed on a reference hardware platform. Actual performance will vary depending on hardware, configuration and parameter options.

Effects can also return the pre-defined constant effectIsRealtime as their speed. This means that the effect will execute as quickly as frames can be sent to it for rendering.